Introduction

This document details the Atlas of Living Australia style guide for creating html files from R Markdown

Style Template

A test of a chunk

library(kableExtra)
library(tidyverse)

# a table
head(mtcars, n=5) %>%
  kbl() %>%
  kable_styling()

	mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
Mazda RX4	21.0	6	160	110	3.90	2.620	16.46	0	1	4	4
Mazda RX4 Wag	21.0	6	160	110	3.90	2.875	17.02	0	1	4	4
Datsun 710	22.8	4	108	93	3.85	2.320	18.61	1	1	4	1
Hornet 4 Drive	21.4	6	258	110	3.08	3.215	19.44	1	0	3	1
Hornet Sportabout	18.7	8	360	175	3.15	3.440	17.02	0	0	3	2

Getting started

Use ALA Template

Create a new R Markdown document by selecting File –> New File –> R Markdown

In the left window menu, select New Template. Then select the ALA Template

Add your information

In the top 3 lines, add your document title, your name and the date. Leave the remainder of the .yaml options unchanged.
Next, scroll down to the code chunk named upper right bio. This code chunk adds your image and links to your personal websites
- Save your preferred picture as “picture.jpg” in the current directory
- Add the urls you wish to link to for the correct websites & icons

`{r upper right bio, echo = FALSE}
htmltools::withTags(
  div(id = "pictureposition",
      
      
# Save your own picture as "picture.jpg" to local directory
      img(src = knitr::image_uri("picture.jpg"),
          class = "clipped", 
          style = 'height:100px'),
      
# Add links to personal accounts below and uncomment
      div(id = "linkposition",
          # a(href="your-url",              # twitter
          #   class="fab fa-twitter",
          #   style = "text-align:center"),
          # a(href="your-url",              # github
          #   class="fab fa-github",
          #   style = "text-align:center")
          # a(href="your-url",              # linkedIn
          #   class="fab fa-linkedin",
          #   style = "text-align:center")
          )))
`

Knit to HTML

Click the Knit button in the upper menu (below file tabs, above script) to create an HTML file. A preview of your knitted HTML document can be viewed in the right pane. Code must run successfully from start to finish for a file to be Knit.

In the R Studio viewer pane, click the “Show in New Window ” button to view the page in your browser.

Push to Github

Reproducible workflows

Safe paths

Using setwd() to set a working directory can create issues for folder paths. They often are a cause of issues when making reproducible workflows.

Instead, use the here() function from the here package to build the path where you read and write files. here() automatically creates paths relative to the top level directory.

Read a full description of how to use the here() function to create safe paths in Chapter 3 of What They Forgot to Teach You About R

For example:

library(ggplot2)
library(here)

df <- read.delim(here("projects", , "style_guide", "data.csv"))
p <- ggplot(df, aes(x, y)) + geom_point()
ggsave(here("plots", "foofy_scatterplot.png"))

To set the project root path according to your current code file:

here::i_am("style_guide.rmd")

Make understandable code

Code chunk size

In writing, we use sentences and paragraphs of varying lengths to build a flowing, logical story or argument. In the same way, code chunks can be used to structure lines of code to build a flowing, logical analysis or plot.

Code chunks should be brief. They should also offer notes or visual output that provides context to any transformations or outputs. Users should be able to follow each transformation that is made to your data, each output that results from a transformation, and any final output.

There is no single correct code chunk size - you must use your best judgement. If it seems that the result of one or several lines of code is unclear a potential reader, you may need to split the code chunks to make the results easier to follow.

Brief summaries

For others to understand what your code does and why you made the choices you did, it is helpful to include brief summaries or your logic or what each line of your code does. It is also good to provide a brief interpretation of model output

Style code using `styler`

Use the styler package to ensure your code is formatted correctly and/or consistently, The styler package formats your code according to the tidyverse style guide (or another custome style) prior to uploading a finished file document.

See the styler github and tidyverse pages for more information

Install the styler package to add style buttons to your R Markdown Addins dropdown menu. Clicking Addins -> style active file will reformat the code in your active file. Clicking ** Addins** -> style active section will reformat code in your current section.

Alternatively, you style_file() or style_text() can be run in the console.

Output style

See the R Markdown cheat sheet for more information on R Markdown formatting

For tips to make your R Markdown output pretty, see Pimp my RMD by Yan Holtz

Tables

Several packages can create tables with nice formatting.

One example is kableExtra:

library(kableExtra)
kable(
  head(mtcars, n=5)) %>% kable_styling()

	mpg	cyl	disp	hp	drat	wt	qsec	vs	am	gear	carb
Mazda RX4	21.0	6	160	110	3.90	2.620	16.46	0	1	4	4
Mazda RX4 Wag	21.0	6	160	110	3.90	2.875	17.02	0	1	4	4
Datsun 710	22.8	4	108	93	3.85	2.320	18.61	1	1	4	1
Hornet 4 Drive	21.4	6	258	110	3.08	3.215	19.44	1	0	3	1
Hornet Sportabout	18.7	8	360	175	3.15	3.440	17.02	0	0	3	2

kableExtra is also able to be used using magittr or base piping:

mtcars %>% 
  group_by(gear) %>% 
  summarise(cyl = mean(cyl),
            disp = mean(disp)) %>%
  kbl() %>%
  kable_styling()

gear	cyl	disp
3	7.466667	326.3000
4	4.666667	123.0167
5	6.000000	202.4800

head(mtcars |>
  subset(select = c("cyl", "disp", "gear")), n = 5) |>
  kbl() |>
  kable_styling()

Figures

Controlling the size of figures can help when you want people to focus on trends of many plots or on details of a single plot.

You can control how many columns your plots created in a chunk are printed into.
Add out.width = c("50%", "50%"), fig.show = "hold":

``{r out.width=c('50%', '50%'), fig.show='hold'}
boxplot(1:10)
plot(rnorm(10))
`

Control other parts of figure output in the chunk header as well. For example:

``{r, fig.align="center", fig.width=6, fig.height=6, fig.cap="Figure: Here is a really important caption."}

library(tidyverse)
mpg %>%
  ggplot( aes(x=reorder(class, hwy), y=hwy, fill=class)) + 
    geom_boxplot() +
    xlab("class") +
    theme(legend.position="none")

Figure: Here is a really important caption.

Model output

Run a model and want to show output? Use the model_parameters() function from the parameters package to make your output clear and organised. The model_parameters() function can be considered as a lightweight alternative to broom::tidy():

library(parameters)
model <- lm(Sepal.Width ~ Petal.Length * Species + Petal.Width, data = iris)

# regular model parameters
model_parameters(model)

## Parameter                           | Coefficient |   SE |         95% CI | t(143) |      p
## -------------------------------------------------------------------------------------------
## (Intercept)                         |        2.89 | 0.36 | [ 2.18,  3.60] |   8.01 | < .001
## Petal.Length                        |        0.26 | 0.25 | [-0.22,  0.75] |   1.07 | 0.287 
## Species [versicolor]                |       -1.66 | 0.53 | [-2.71, -0.62] |  -3.14 | 0.002 
## Species [virginica]                 |       -1.92 | 0.59 | [-3.08, -0.76] |  -3.28 | 0.001 
## Petal.Width                         |        0.62 | 0.14 | [ 0.34,  0.89] |   4.41 | < .001
## Petal.Length * Species [versicolor] |       -0.09 | 0.26 | [-0.61,  0.42] |  -0.36 | 0.721 
## Petal.Length * Species [virginica]  |       -0.13 | 0.26 | [-0.64,  0.38] |  -0.50 | 0.618

model_parameters() can also be used for parameter standardization:

# standardized parameters
model_parameters(model, standardize = "refit")

## Package 'effectsize' required to calculate standardized coefficients. Please install it.

## Parameter                           | Coefficient |   SE |         95% CI | t(143) |      p
## -------------------------------------------------------------------------------------------
## (Intercept)                         |        2.89 | 0.36 | [ 2.18,  3.60] |   8.01 | < .001
## Petal.Length                        |        0.26 | 0.25 | [-0.22,  0.75] |   1.07 | 0.287 
## Species [versicolor]                |       -1.66 | 0.53 | [-2.71, -0.62] |  -3.14 | 0.002 
## Species [virginica]                 |       -1.92 | 0.59 | [-3.08, -0.76] |  -3.28 | 0.001 
## Petal.Width                         |        0.62 | 0.14 | [ 0.34,  0.89] |   4.41 | < .001
## Petal.Length * Species [versicolor] |       -0.09 | 0.26 | [-0.61,  0.42] |  -0.36 | 0.721 
## Petal.Length * Species [virginica]  |       -0.13 | 0.26 | [-0.64,  0.38] |  -0.50 | 0.618

Code chunk options

See the R markdown documentation to view chunk options.

Example: `echo` and `eval`

Readers should be able to identify where every file in a workflow comes from (little is more frustrating than wondering where a required data file is located). Code used to load or extract data (from galah, for example) should be clearly identified.

However, some code takes a very long time to run and you may have saved it locally or in a repository to save time and/or space. In this case, it is possible to show code without running it.

Add eval = FALSE to the chunk header to display the code but prevent the chunk from running:

``{r, eval = FALSE}
ala_counts(group_by = "phylum")
`

You can then load a local file in the background, without showing the code.

Add echo = FALSE to your chunk header to run the code but prevent the chunk from displaying:

``{r, echo = FALSE}
data <- readRDS(file = "local_file.rds")
`

Style Guide

by Dax Kellie

04/06/2021

Introduction

Style Template

Getting started

Use ALA Template

Add your information

Knit to HTML

Push to Github

Reproducible workflows

Safe paths

Make understandable code

Code chunk size

Brief summaries

Style code using `styler`

Output style

Tables

Figures

Model output

Code chunk options

Example: `echo` and `eval`

Style Guide

by Dax Kellie

04/06/2021

Introduction

Style Template

Getting started

Use ALA Template

Add your information

Knit to HTML

Push to Github

Reproducible workflows

Safe paths

Make understandable code

Code chunk size

Brief summaries

Style code using styler

Output style

Tables

Figures

Model output

Code chunk options

Example: echo and eval

Style code using `styler`

Example: `echo` and `eval`